home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / macros / lollipop / lollipop.hqx / Lollipop Manual / struct.tex < prev    next >
Text File  |  1992-11-19  |  8KB  |  209 lines
  1. % Struct.tex copyright 1992 Victor Eijkhout
  2. %
  3. \Chapter The structure of Lollipop
  4.  
  5. Lollipop provides tools for realizing the style or layout of a
  6. document. Some of these tools are macros ready to be used by the end
  7. user; they concern for instance selection of fonts.
  8. Others, the `generic constructs', are for the style designer so that
  9. she can use them to program the macros for the user.
  10.  
  11. \Section[sec:doc-start-stop] Lollipop Files
  12.  
  13. Any Lollipop document has to have a \cs{Start} and \cs{Stop} command.
  14. Before the \cs{Start} there can be style definition commands, but no
  15. text. For a number of reasons it is advisable to put as much of the
  16. style definition before the \cs{Start} command as possible.
  17.  
  18. \ImpNote
  19. Before the \cs{Start} command, \cs{everypar} contains an error
  20. message. The start command installs the default value for
  21. \cs{everypar}.
  22. \ImpNoteStop
  23.  
  24. Both the start and the stop file load the \file{.aux} auxiliary file.
  25. None of this should concern you, really. Expert users who want to
  26. have certain actions performed at the start of the document may want
  27. to use \refcs{StartCommand} to specify what they wish done. See
  28. section~\ref[sec:adapt-distance] for an example.
  29.  
  30. \Section Generic Constructs
  31.  
  32. \label[generic:construct]\label[option:macro]
  33. There are five `generic constructs': headings, lists, text blocks, page
  34. grids, and external items. For each construct type there is a defining
  35. command, for instance \cs{DefineHeading}
  36. which is followed a list of `options', terminated by the word `Stop'.
  37.  
  38. Options (possibly with values) have to be separated by a
  39. space or a line end; the keyword \opt{Stop} has to be followed by a
  40. space or a line end.
  41. Options may have zero, one or two values; if there are values, then
  42. the first one is separated from the option by a colon, the second is
  43. separated from the first by an equals sign.
  44.  
  45. \Ver>\DefineFoo:Bar optiona optionb optionc:value
  46.     optiond:valuea=valueb optione
  47.     optionf Stop<Rev
  48.  
  49.  As a result of this definition, a command
  50. \cs{Bar} is created. If the \con{Foo} construct was a \con{List} or
  51. \con{TextBlock}, an additional command \cs{BarStop} is created.
  52.  
  53. This command can then be used in the ordinary way, for instance
  54. after \ver>\DefineHeading:Foo> you can type
  55. \Ver>\Foo The title<Rev and after \ver>\DefineList:Foo> you can type
  56. \Ver>\Foo
  57. \item One item
  58. \item And another
  59. \FooStop<Rev
  60.  
  61. \ImpNote
  62. Actually, this `Stop' business can be customized for other languages.
  63. The file \file{tools} has the following lines:
  64. \Ver>
  65. \def\stop@command@suffix{Stop}
  66. \def\stop@command{\@command\stop@command@suffix}<Rev
  67. \ImpNoteStop
  68.  
  69. \Section Options
  70.  
  71. Options are mostly used to specify how a construct will look. Some
  72. options, for instance \opt{title}, indicate material that will appear
  73. on the page. Other options are interpreted as commands, for instance
  74. \opt{IndentAfter:yes} in the definition of a heading indicates that
  75. the first paragrah after such a heading will indent.
  76.  
  77. In addition to keywords that only exist as options, commands can
  78. be used as options. Also, single characters are accepted as options.
  79. For instance a definition of a subsection heading can contain: 
  80.  
  81. \Ver>\DefineHeading:SubSection 
  82.     [...]
  83.     SectionCounter . SubSectionCounter
  84.     [...] Stop<Rev
  85. (Here and later the \n{[...]} will denote arbitrary omitted text.)
  86. This definition contains the commands \cs{SectionCounter} and
  87. \cs{SubSectionCounter} and the \n{.} character.
  88.  
  89. If a number of options appears together in a number of constructs it
  90. is convenient to have an abbreviation for them. This can be done with the command
  91. \refcs{OptionsMacro} as follows. The options that appear together are
  92. given a common name
  93.  \Ver>\OptionsMacro:baz=optiona optionb:value optionc
  94.     Stop<Rev
  95. (be sure to leave
  96. no spaces around the equals sign) and this name is then used as
  97.  \Ver>    macro:baz<Rev
  98. in the option list wherever the options are needed. 
  99.  
  100. This is for
  101. instance a good way of specifying identical white space around all
  102. sorts of constructs without duplicating the typing each time.
  103. However, it is only for your convenience: it doesn't save any \TeX\
  104. resources or processing time.
  105.  
  106. \ImpNote
  107. \iSection Defining Generic Constructs
  108.  
  109. The \cs{Define...} commands are not defined explicitly, instead they
  110. are generated by a call such as
  111. \Ver>    \@GenericConstruct{Heading}<Rev
  112. Full definition:
  113. \Ver>\def\@GenericConstruct#1{<Rev
  114. to be used as \ver>\@GenericConstruct{Foo}>;
  115. \Ver>    \append@to@list{@gencons}{\\#1;}<Rev
  116. book keeping of existing generic constructs;
  117. \Ver>    \csarg\newtoks{#1@defaults}
  118.     \csn #1@defaults\ecs{}<Rev
  119. default commands to be executed whenever 
  120. an instance of this construct
  121. is defined;
  122. \Ver>    \csarg\def{add@#1@default}##1%
  123.              {\append@to@list{#1@defaults}{##1}}<Rev
  124. the command \cs{add@Foo@default}
  125. to add defaults for this construct;
  126. \Ver>    \Install@Noops{#1}<Rev
  127. possibility to generate error msgs for the use of an option that is
  128. not allowed for this type of construct;
  129. \Ver>    \csarg\def{Define#1}:##1 {<Rev
  130. instances of this construct will be defined
  131. by a statement like \ver>\DefineFoo:Bar>;
  132. \Ver>        \def\@name{##1}\def\@class{#1}
  133.         \Tmessage[def]{Defining a #1: ##1}<Rev
  134. \ver>DefineFoo:Bar> leads to \cs{@name} begin \n{Bar},
  135. \cs{@class} being \n{Foo};
  136. \Ver>        \the\generic@defaults
  137.         \csarg\the{#1@defaults}<Rev
  138. unpack token lists of generic and specific default actions;
  139. \Ver>        \Get@Items}<Rev
  140. start recursive processing of list of options. This ends the
  141. definition of \cs{DefineFoo}; the definition of 
  142. \cs{@GenericConstruct} ends with
  143. \Ver>    \csarg\def{@#1Option}##1%
  144.        {\csarg\def{#1@##1}####1####2}<Rev
  145. which defines the \cs{@FooOption} macro; see~\ref[imp:option].
  146. \Ver>    }<Rev
  147.  
  148. \iSection Items Processing
  149.  
  150. Processing the list of items is recursive; at the end some concluding
  151. actions have to be taken, mostly the actual definition of the
  152. construct.
  153.  
  154. First we have to filter out empty arguments, which can be caused by
  155. the use of option macros (\ref[option:macro], \ref[imp:option:macro]).
  156.  
  157. \Ver>\def\Get@Items#1 {\if\EmptyList{#1}\let\get@next@item\Get@Items
  158.     \else\def\get@next@item{\@Get@Items#1 }\fi
  159.     \get@next@item}<Rev
  160.  
  161. Next, check if the argument is \opt{Stop} (defined by
  162. \ver>\NewDummy{Stop}>, \ref[imp:new:dummy]), in which case you
  163. have reached the end of a generic definition, and can start performing
  164. the final rites. Otherwise, dissect this option item 
  165. and go on with the rest
  166. of the options.
  167. \Ver>
  168. \def\@Get@Items#1 {\let\get@next@item=\Get@Items
  169.     \csarg\ifx{#1}\Stop
  170.           \the\generic@stop@defaults
  171.           \let\get@next@item=\relax
  172.     \else \Item@or@Macro#1::. \fi \get@next@item}<Rev
  173.  
  174. The \n{::.} concluding \cs{Item@or@Macro} accomodates one,
  175. possibly empty, argument.
  176.  
  177. \iSection Options\label[imp:option]\label[imp:option:macro]
  178.  
  179. Options can either be specific, defined as
  180. \Ver>\@FooOption{Bar}{ [...] }<Rev
  181. in which case the option \opt{Bar} can only be used inside
  182. a call to \cs{DefineFoo},
  183. or they can be generic, defined as
  184. \Ver>\@GenericOption{Bar}{ [...] }<Rev
  185. For both definitions, the definition text can use up to two parameters.
  186. Parameters are given to the options as
  187. \Ver>    optiona:par1 optionb:par1=par2<Rev
  188.  
  189. Specific options are defined by the line
  190. \Ver>
  191.     \csarg\def{@#1Option}##1%
  192.          {\csarg\def{#1@##1}####1####2}<Rev
  193. in \cs{@DefineGenericConstruct}; a call
  194. \Ver>\@FooOption{Bar}{ ... }<Rev
  195. expands to
  196. \Ver>\def\Foo@Bar#1#2{ ... }<Rev
  197. Generic options are defined by the
  198. following command:
  199. \Ver>\def\@GenericOption#1{
  200.     \append@to@list{@GenericOptions}{\\#1;}
  201.     \csarg\def{Option@#1}##1##2}<Rev
  202. A call
  203. \Ver>\@GenericOption{Bar}{ ... }<Rev
  204. expands to
  205. \Ver>\def\Option@Bar#1#2{ ... }<Rev
  206.  
  207. \ImpNoteStop
  208.  
  209.